/*
 * Copyright 2009 SHOP.COM
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.shop.opensocial.mediated.services;

import javax.servlet.http.HttpServletRequest;

/**
 * Returns various constants used by the underlying implementation
 *
 * @author Jordan Zimmerman
 */
public interface ContainerScriptsAndConstantsMediator
{
	/**
	 * Return the value of the security token URL parameter
	 *
	 * @param request current request
	 * @return token value or null
	 */
	public String		getSecurityTokenFromURL(HttpServletRequest request);

	/**
	 * Return HTML that must be output in any container page that will contain gadgets
	 *
	 * @param hostname hostname of the container page
	 * @param ssl true if page is SSL
	 * @return output
	 */
	public String		getContainerIncludes(String hostname, boolean ssl);

	/**
	 * Return the URL to use for gadget iframes
	 *
	 * @param iframeHostname the hostname to use for the iframe
	 * @param parentHostname the hostname of the parent/container of the iframe
	 * @param ssl if true, make the URL ssl
	 * @param securityTokenValue value to set for the security token   @return iframn URL
	 * @return the URL
	 */
	public String		makeGadgetIFrameURL(String iframeHostname, String parentHostname, boolean ssl, String securityTokenValue);

	/**
	 * Selector for {@link ContainerScriptsAndConstantsMediator#getContainerRegistration(RegistrationTypes, String)}
	 */
	public enum RegistrationTypes
	{
		/**
		 * Registration for gadgets.window.setTitle(). The callback function's signature should be:
		 * 		function(applicationID, title)
		 */
		SET_TITLE,

		/**
		 * Registration for gadgets.views.requestNavigateTo(). The callback function's signature should be:
	 	 * 		function(applicationID, view, options)
		 */
		REQUEST_NAVIGATE_TO,

		/**
		 * Registration for gadgets.window.adjustHeight(). The callback function's signature should be:
	 	 * 		function(applicationID, height)
		 */
		DYNAMIC_HEIGHT
	}

	/**
	 * Returns the HTML to include in the container to register an RPC callback.
	 *
	 * @param type which callback to register for
	 * @param callbackFunctionName the Javascript function name to call
	 * @return output
	 */
	public String		getContainerRegistration(RegistrationTypes type, String callbackFunctionName);
}
